home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 4 / Apprentice-Release4.iso / Source Code / Add-Ons / MPW / MPW noweb 2.7 / src / xdoc / noindex.nw < prev    next >
Encoding:
Text File  |  1995-05-30  |  3.1 KB  |  162 lines  |  [TEXT/MPS ]
  1. <<*>>=
  2. .TH NOWEB 1 "local <<noweb documentation date>>"
  3. .SH NAME
  4. noindex \- build external index for noweb document
  5. .SH SYNOPSIS
  6. .B noindex \fIbasename\fP\fR[\fP.tex\fR]
  7. .SH DESCRIPTION
  8. .I noindex
  9. looks through 
  10. .I LaTeX
  11. .B .aux
  12. files for identifiers that should go in a
  13. .I noweb
  14. external index.
  15. It sorts all identifiers and writes the results on
  16. .I basename\fB.nwi\fP.
  17. .SH NOWEB INDEXING STRATEGIES
  18. A 
  19. .I noweb
  20. program consists of one or more files.
  21. In the simple case, these files are run through
  22. .I noweave
  23. together, to produce a single
  24. .I LaTeX
  25. file.
  26. .I noweave \-index
  27. suffices to produce an index and cross-referencing information;
  28. neither 
  29. .I nodefs
  30. nor
  31. .I noindex
  32. is required.
  33. .PP
  34. When a 
  35. .I noweb
  36. program
  37. consists of several source files, it is often better to run each source file
  38. through 
  39. .I noweave
  40. to produce its own 
  41. .I LaTeX 
  42. file, then use
  43. .I noindex
  44. to produce an external index.
  45. This technique has several advantages:
  46. .IP
  47. The line numbers in the 
  48. .I LaTeX
  49. files correspond to the line numbers in the source files, so it is easier
  50. to diagnose 
  51. .I LaTeX
  52. errors.
  53. .IP
  54. The
  55. .I LaTeX
  56. .B "\\\\includeonly"
  57. feature can be used, making it possible to format parts of large programs while retaining
  58. complete cross-reference information.
  59. .IP
  60. When used with
  61. .I make(1),
  62. the technique 
  63. avoids running 
  64. .I noweave
  65. over source files that have not changed.
  66. .IP
  67. Using the external index places fewer demands on \fILaTeX\fP's memory,
  68. making it read its
  69. .B .aux
  70. files much more quickly.
  71. .PP
  72. The disadvantages are that 
  73. .I nodefs
  74. and 
  75. .I noindex
  76. are needed for full cross-referencing and a properly sorted index.
  77. .SH EXAMPLE
  78. This example assumes a 
  79. .I noweb
  80. program of three source files:
  81. .B a.nw, b.nw, 
  82. and
  83. .B c.nw.
  84. The file
  85. .B doc.tex
  86. is assumed to contain 
  87. .I LaTeX
  88. boilerplate, including the commands
  89. .IP
  90. \\noweboptions{externalindex}
  91. .nf
  92. \\include{a}
  93. \\include{b}
  94. \\include{c}
  95. .fi
  96. .PP
  97. The first sequence of steps is to create a file listing all the
  98. identifiers defined anywhere in 
  99. .B a, b,
  100. or 
  101. .B c.
  102. .IP
  103. nodefs a.nw > a.defs
  104. .nf
  105. nodefs b.nw > b.defs
  106. nodefs c.nw > c.defs
  107. sort -u a.defs b.defs c.defs | cpif all.defs
  108. .fi
  109. .PP
  110. Using
  111. .I sort -u
  112. and
  113. .I cpif(1)
  114. avoids changing
  115. .B all.defs
  116. unless the set of identifiers changes.
  117. This technique, used in a Makefile, avoids unnecessary rebuilding.
  118. .PP
  119. The next series of steps is to create
  120. .I LaTeX
  121. files with full cross-reference information for all identifiers.
  122. .IP
  123. noweave -n -indexfrom all.defs a.nw > a.tex
  124. .nf
  125. noweave -n -indexfrom all.defs b.nw > b.tex
  126. noweave -n -indexfrom all.defs c.nw > c.tex
  127. .fi
  128. .PP
  129. The final steps run
  130. .I LaTeX
  131. once to create
  132. .B .aux
  133. files, then
  134. .I noindex 
  135. to create the index,
  136. then
  137. .I LaTeX
  138. again to format the complete document.
  139. .IP
  140. latex doc
  141. .nf 
  142. noindex doc
  143. latex doc
  144. .fi
  145. .PP
  146. In a Makefile,
  147. .I noindex
  148. can be run before every invocation of
  149. .I LaTeX.
  150. .SH BUGS
  151. .I noindex
  152. is distributed in awk and Icon versions.
  153. The awk version is slow and does a poorer job sorting.
  154. .PP
  155. There is no comparable machinery to make it possible to use multiple files 
  156. with the HTML back end.
  157. .SH SEE ALSO
  158. .I noweave(1), nodefs(1), cpif(1)
  159. .SH AUTHOR
  160. Norman Ramsey, Bellcore.
  161. Internet address \fBnorman@bellcore.com\fP.
  162.